Chip 1999 August/Chip_1999-08_cd.bin/zkuste/MacOS/Files/His.sit/Hi's Universal Saver v.1.6.0 ∫/Parts to Install/Menu Events 1.3.1/Menu Events Help (text)

Text File | 1998-01-07 | 44KB | 986 lines

╩
Menu Events 1.3.1

December 13, 1997



Disclaimer and Copyright Notice


Menu Events is a free utility which lets you control another application╒s
menu commands by sending it an Apple event.  The author, Ross Brown,
makes no warranty, either express or implied, with respect to this
software, its performance, merchantability, or suitability for any
particular purpose.  People using the Menu Events utility do so at their
own risk.  The author disclaims all liability for loss of data, mechanical
damage, or other losses suffered while using the Menu Events utility.

Menu Events is an AWOL Software Production, Copyright ⌐ 1994-7 Ross
Brown.  All rights reserved.  Permission is granted to make and distribute
copies of this software, provided this disclaimer and copyright notice are
preserved on all copies.  The software may not, however, be sold or
distributed for profit, or included with other software which is sold or
distributed for profit, without the permission of the author.

There are no site license fees for the use of Menu Events within an
organization.  The author encourages you to make and distribute as many
copies of the system extension as you wish, for whomever you wish, as
long as it is not for profit.  Menu Events is part of a set of cooperating
programs, AWOL Utilities.  The tutorial help you are reading is designed
for handling by the help server application Help on Wheels, which is also
part of AWOL Utilities.



Distribution Policy


New versions of individual AWOL Utilities programs, including Menu
Events, are available by anonymous FTP from popular archive sites
including <ftp://sumex-aim.stanford.edu/info-mac/> and its various
mirror sites, such as <ftp://mirrors.aol.com/pub/info-mac/>.

For the latest information about AWOL software, including AWOL Utilities,
please visit the AWOL Web page at <http://www.magma.ca/~awolsp/>.

Support for AWOL Utilities is through Internet mail at
<mailto:[e-mail]>.  The software is not available by
FTP from this site.  The address for paper correspondence is AWOL
Software Productions, PO Box 24207, Hazeldean RPO, Kanata, Ontario,
Canada K2M 2C3.

Macintosh users who do not have access to electronic sources of free and
shareware software may obtain a copy of AWOL Utilities by sending a
self-addressed stamped envelope and an 800K (or larger) formatted
diskette to the author at the above address.  U.S. users are reminded that
postage from Canada in 1997 is C$0.52 up to 30 grams (1 oz.), C$0.77 up
to 50 grams (1 3/4 oz.), and C$1.17 up to 100 grams (3 1/2 oz.).
US$0.50, US$0.75, and US$1.00 in coin is acceptable in place of stamps
for the respective weights.  People outside the U.S. and Canada may send
an international postal reply coupon instead of Canadian stamps (available
from any post office).  Please use sturdy envelopes, preferably cardboard
disk mailers.  (Mailers over 5 mm (1/5") thick require C$1.17 postage to
the U.S.)
Please do not send return envelopes with non-Canadian
stamps, as Canada Post will not accept them.



About AWOL Software Productions


AWOL Software Productions specializes in custom development of
software for the Mac OS.  Since its inception in 1990, AWOL has
developed a number of programs which enhance the Mac OS user
experience, working in nearly every part of the Macintosh Toolbox.  If
you have a short-term programming task or product idea but lack the
staff to do the expert design, coding, and documentation, we invite your
inquiry.

Virtual Desktop is AWOL╒s best-known effort, serving the desktop
expansion needs of thousands of Mac users around the world.  Later in
1997, AWOL will release a new commercial version 2.0 to replace the
freeware version contained in the AWOL Utilities package.  Please contact
us at <mailto:[e-mail]> for feature and ordering
information.

Users who want more out of the Mac╒s speech capabilities should check
out MacYack Pro, a jointly developed package of speech tools marketed by
Scantron Quality Computers (<http://www.lowtek.com/macyack/>;
<mailto:[e-mail]>; 20200 Nine Mile Rd., St. Clair Shores, MI
48080).



Purpose


The big trend these days in Macintosh software is toward more
integration between applications.  Increasingly, developers achieve this
integration by using the Apple event interfaces of other applications, and
by defining their own suites of Apple events for other applications to use.

Because there are far more clients than servers in the world of Apple
events, there is a large number of ╥high-level-event-aware╙ applications
which support program linking, using Apple events to control other
applications (or just to be modern), but not offering any interface of their
own.  Apart from the Required suite mandated by Finder, the functionality
of these applications is beyond the reach of scripting utilities and other
programs that send Apple events.  Menu Events is a utility which opens up
this demi-monde of dabblers and dilettantes to the glories of Apple event
controllability.  Applications which are by their nature only
high-level-event-aware become scriptable and recordable Apple event
servers.

If you regard an application╒s collective user interface in terms of a set
of available functions, then take subsets according to how the user can
access these functions (Command-key combination, button click, menus,
and so on), you will usually find that the subset for menus is largest.  This
is because menus are intended as a baseline for the user interface;
however else you can do something, you should be able to do it with menus
as well.  Often a function is not available in a certain mode, but a menu
selection will shift the application into that mode, then another will access
the function.  This conformity is an asset of the Macintosh operating
system which can be exploited to offer a fairly general means of
controlling other applications.



Who Can Use Menu Events?


You do not need AppleScript, or any other optional software package, for
Menu Events to work.  It only requires System 7.

However, it has no user interface of its own.  It only enables programs to
do something they would not otherwise be able to do, namely, invoke
another application╒s menu commands.

Any program you write, or any application which lets you compose and
send Apple events (such as a general scripting utility, or Maybe, part of
AWOL Utilities), can send a Menu event to any suitably modern application
and hope for a response.  Whether or not a particular application
cooperates depends on how it was programmed, but any application
programmed according to the published instructions of Apple Computer
will cooperate, with a bit of coaxing.
See the section entitled ╥Limitations╙ for more information.

Menu events can be received from any machine on the AppleTalk network,
subject to the usual Users & Groups program linking permission scheme.
This allows you to use Menu events to control applications from a remote
location.

If you have AppleScript, you should place the ╥Menu Events Scripting
Addition╙ file in your ╥Scripting Additions╙ folder.  This will allow you
to use Menu events in your scripts.  (Unlike most scripting additions, this
one only describes event terminology, and does not implement the event
handlers themselves, so it is useless without the Menu Events extension.)
╥Menu Events Sample Script╙ shows the sort of thing you can do with the
scripting addition file installed.  Before writing a script to control a
target application, you should try recording its menu actions using your
script editor.  If the target application supports program linking, and the
Caps Lock key is down, these actions will be recorded as Menu Events
script commands.



What Does Menu Events Do?


Menu Events is a system extension.  Once you have placed it in your
Extensions folder and restarted your Macintosh, it adds a small suite of
Apple events (╥Menu events╙) to the set supported by every
high-level-event-aware application.  Also, if the Caps Lock key is down,
it alters menu selection logic so that the selection is recorded as a Menu
event.  This capability allows a script editor to record menu actions as
script commands.

Many people are justly wary of control panels and system extensions,
because of the conflicts they often cause with System software and with
each other.  These conflicts usually result from competitive trap patching.

Menu Events installs a GetNextEvent filter and patches the MenuSelect
trap at system startup to enable the Apple event recording capability, and
installs an Apple event handler in the system dispatch table.  The Apple
event handler cannot conflict with any other, because it is bound
specifically to the Menu event class.  Menu Events does patch some traps
╥on the fly╙ to simulate menu selection, but the patches remove
themselves immediately.

There are three events defined in the suite, and they work as follows.
See the section entitled ╥Menu Events Suite╙ for more information on the
Menu Events suite.


Query Menu List Event

This event, with no parameters, queries the menu list of the target
application.  If the application is high-level-event-aware, not
background-only, and has a menu bar, it will return a list of records, each
containing a menu ID (integer), a title (string), an enable/disable
(Boolean), and a menu definition procedure resource ID (integer)
parameter.  If you do not know the IDs or titles of the target application╒s
menus, this is one way to find out.  (Another way is to press the Caps
Lock key and record menu actions using a script editor; yet another is to
use the Menu Grabber application, also part of AWOL Utilities.)  Be aware
that menu IDs do not have to agree with 'MENU' resource IDs, though they
often do.
See the section entitled ╥Suggestions for Use╙ for more information on
Menu Grabber.

System menus (Keyboard, Help, Application), hierarchical menus, and
pop-up menus do not appear in this list, but the Apple menu does.

NOTE:  The standard menu definition procedure ('MDEF') resource ID is 0.
A value of -1 indicates that the menu definition procedure is not a
resource.  Non-standard menu definition procedures may have abnormal
ways of counting, disabling, and displaying menu items, so be careful with
them.


Query Menu Event

This event, given a menu ID (integer) and/or menu title (string)
parameter, queries the items of a certain target application menu.  If the
application has a menu with that ID and/or title, be it a regular, system,
hierarchical, or pop-up menu, it will return a list of records, one per
menu item, each containing a menu item ID (integer), an item text
(string), an enable/disable (Boolean), a mark character (integer), an icon
ID (integer), a style value (integer), and a Command character (integer)
parameter.  The items are numbered starting from 1 at the top end of the
menu.  Separators appear as disabled items with an item text of ╥-╙.

This event simulates a simple click in the application╒s menu bar, to force
it to bring its menus up to date.

You may optionally include Boolean parameters to indicate which modifier
keys (Shift, Control, Option, Command) are pressed at the time of the
simulated menu bar click, in case this makes a difference in the content of
the menu.

This event does work for menus which use a non-standard menu definition
procedure ('MDEF'), but the results may or may not reflect what you see
when you pull down the menu, depending on how the procedure was
programmed.

This event brings the target application to the front before forcing the
menu bar click upon it.  If the sender was on the same machine, and was
previously in front, it returns to the front after the menu query is
complete.
See the section entitled ╥How Does Menu Events Work?╙ for more
information about the method by which Menu Events activates the target
application.


Select Menu Item Event

This event, given a menu ID (integer) and/or menu title (string)
parameter and a menu item ID (integer) and/or menu item text (string)
parameter, asks the application to act as though the user pulled down that
menu and selected that item.  This does not work for the Keyboard and
Application menus, which are not under the control of the application, nor
for the upper (System-defined) part of the Help menu, but it works for
any regular, application-defined, enabled menu item.

If you use the menu item text parameter to specify the menu item to
select, be sure to match any special characters in the text, especially the
ellipsis ('╔') character which often appears at the end of the string,
which is not the same as three period characters, despite its appearance.

You may optionally include Boolean parameters to indicate which modifier
keys (Shift, Control, Option, Command) are pressed at the time of the
simulated menu item selection, in case this makes a difference in the
effect of the selection.

This event does work for menus which use a non-standard menu definition
procedure ('MDEF'), but the results may or may not reflect what happens
when you select from the menu, depending on how the procedure was
programmed.

This event brings the target application to the front before forcing the
menu selection upon it.  If the sender was on the same machine, and was
previously in front, it returns to the front after the menu action is
complete.
See the section entitled ╥How Does Menu Events Work?╙ for more
information about the method by which Menu Events activates the target
application.



How Does Menu Events Work?


When you send a Query Menu List event, the ideal application dispatches
the resulting high-level event as an Apple event without looking at it.  The
event handler provided by Menu Events forms a reply to the query on the
basis of the application╒s menu list structure.  Through all of this, the
application stays in the background or in the foreground, wherever it was
before.

When you send a Query Menu or Select Menu Item event, the same things
happen, but the event handling is more complex.

First, it verifies that the given menu is valid.  If not, it returns
noSuchMenuErr.

Second, it asks for the application to be brought to the front for user
interaction, because it could be dangerous to feed the target application a
menu bar click while it is in the background, something that never happens
in normal operation.  If it is refused, it returns errAENoUserInteraction.

Third, it patches some traps so that it can gain control of menu bar clicks.
If it finds that the patches are already in place, meaning that an earlier
Menu event is still pending, it returns menuEventPendingErr.

Fourth, if everything is OK, it posts an event to simulate a mouse click in
the menu bar, with modifier keys if specified.  The patched traps tell the
application that no menu item was selected.  The patches then remove
themselves.  This step is solely to ensure that the application brings its
menus up to date.

Fifth (in the case of a Select Menu Item event), it verifies that the given
menu item is valid and enabled.  If not, it returns noSuchMenuErr,
noSuchMenuItemErr, or menuItemDisabledErr.  If the menu has a
non-standard menu definition procedure, its way of counting or disabling
items may differ from the norm.  Menu Events assumes that the count and
enable/disable flags are set in the normal fashion.

Sixth (in the case of a Select Menu Item event), it posts an event to
simulate another mouse click in the menu bar, with modifier keys if
specified.  The patched traps tell the application that the given item was
selected.  The patches then remove themselves.  From there, it is exactly
as though the user had actually made the selection.

NOTE:  When replying to any of the three event types, Menu Events
includes a null ╥tattoo╙ parameter to prove that it handled the event,
rather than some handler supplied by the application.  Many Microsoft
applications, for example, bind their own handler over all Apple event
classes, preventing Menu Events from working.  (The handler wouldn╒t be
a problem if it returned errAEEventNotHandled when faced with an
unknown Apple event, as it should.)


User Interaction Policy

The Apple Event Manager implements a complicated but sensible model for
joint sender/receiver control over user interaction.  Menu Events doesn╒t
know which menu selections will really require user interaction, but even
if it did, it would still have to request user interaction just to bring the
target application to the front, where an application always expects to be
when it sees a mouse-down event.

The sending program must set the kAECanInteract or kAEAlwaysInteract
flag in the sendMode parameter to AESend, in order to achieve user
interaction.  It should also set the kAECanSwitchLayer flag, allowing the
target application to come to the front without having to post a
notification request.  If the target application is in the background, and
receives a Menu event with this flag not set, it may go into a notification
wait state, disrupting its usual background event processing behavior.

If both the sending program and target application are in the background,
the kAECanSwitchLayer flag has no effect, and the notification request is
posted anyway.  Since your sending program is indirectly instigating a
user interaction, it should call AEInteractWithUser before sending the
Menu event, if there is any chance that it will be in the background at the
time.  Another approach would be to call SetFrontProcess to activate the
target application before sending it a Menu event.

If the target application is in that rare user interaction state,
kAEInteractWithSelf, where it disallows interaction requested by any
other process, the Menu event handler will respect that state, and refuse
the event.

If the sending and receiving applications are on different machines, the
usual program linking checks apply, namely, Sharing Setup (on/off),
Users & Groups (permission to user), and Finder╒s Sharing (permission to
application).

If the Menu Events extension is locked, using Finder╒s Get Info dialog, then
only target applications which explicitly allow interaction with all
processes can be controlled by remote senders.  If it is not locked, and if
it sees that the user interaction state is kAEInteractWithLocal, which is
the default value, it will momentarily change it to kAEInteractWithAll, so
that events sent from a remote machine are not rejected.  This trick is
necessary for Menu Events to be useful with most target applications,
because most will assume the default interaction state, not expecting any
remote sender to require user interaction.  The icon displayed by Menu
Events at startup shows whether or not the lock is in effect.

IMPORTANT NOTE:  Users of machines where Menu Events is installed
should be careful about which users and applications are enabled for
remote program linking.  In particular, guest users should not be allowed
to do program linking unless Menu Events is locked.


Apple Event Recording Capability

When you are using a high-level-event-aware application on a machine
where Menu Events is installed, menu item selection behavior is modified
if the Caps Lock key is down at the time you release the mouse button.
Menu Events will create a Select Menu Item Apple event to represent the
selection (including parameters for any modifier keys which were
pressed), so that a script editor can record the event as a script
command.  A gentle ╥twang╙ sound confirms that this has happened.
Whether or not it succeeds in recording the event, the menu selection will
be processed in the usual way.

If the application is scriptable in its own right, a script editor may record
two commands when you select an item from its menus.  To prevent this
duplication, you can use the item╒s Command-key equivalent (if any), or
release the Caps Lock key, to suppress the recording capability.

If an application seems to be misinterpreting or not receiving menu
selections, try again with the Caps Lock key up.  The command will not be
recorded, but should work as usual.

NOTE:  While receiving a Select Menu Item event does simulate a menu
selection, it does not cause a Select Menu Item script command to be
recorded.



Suggestions for Use


Menu Events is distributed as part of a free set of cooperating programs,
AWOL Utilities.  This section explains how Menu Events can work in
conjunction with the other programs.


Help on Wheels

Help on Wheels is an efficient and full-featured help server which displays
help files on behalf of client applications.  The help file you are reading is
distributed alongside the Menu Events extension file as a separate Help on
Wheels document.

Because Menu Events is not an application, its help support is limited.  To
read this help, press the Help or Command-? key while the machine is
starting up, and release the key once you see the Menu Events icon with a
help balloon on it.  The help server will open to display the help file after
startup is complete.


Maybe

Maybe, the Finder alias enhancer, has an option allowing you to script a
single Apple event and choose its target.  This Apple event will be sent
just before the alias target is opened or printed.  In this way, you can
achieve the effect of sending a simple Menu event by opening the
converted alias.

Maybe does not require AppleScript or any other scripting system to send
a Menu event.  Many programs, including all kinds of scripting utilities,
offer a similar opportunity to send Menu events to any target application
you choose.


Menu Grabber

AWOL Utilities also contains an application, Menu Grabber, which uses
Menu events to swap any target application╒s menu bar over its own.
This allows you to command most of the application╒s functions from a
remote location, although you will not see anything but the menus.  For
most target applications, Menu Grabber will only be able to select menu
items from a remote machine if the target╒s copy of Menu Events was
unlocked at startup.
See the section entitled ╥User Interaction Policy╙ for more information
about the effect of locking the Menu Events extension.

When Menu Grabber grabs a menu, it adds a disabled item to show the
menu ID.  This may help you if you are writing a program or script to send
a Menu event to the application.



Menu Events Suite


The following is a formal description of the Menu Events suite, in the form
used in the Apple Event Registry.

NOTE:  The C header file ╥Menu Events.h╙╩contains the constant
definitions which appear here.  The ╥Menu Events Scripting Addition╙ file
contains an 'aete' resource which records the following dictionary
information, for the benefit of scripting packages such as AppleScript.
This package also includes a sample script, ╥Menu Events Sample
Script,╙ which demonstrates the usage of the following events and
parameters.


Apple events defined in the Menu Events suite

Name              Requested action

Query Menu List   List all application-defined menus
Query Menu        List all items in a menu
Select Menu Item  Perform a menu command


Query Menu List - list all application-defined menus

A Query Menu List Apple event asks the application to return a list of
records containing information about all menus defined by the application
in its menu bar.  This information includes the Apple menu, but not the
Help, Keyboard, or Application menus.

Event Class       kMEEventClass

Event ID          kAEMEQueryMenuList

Parameters        none

Reply Parameters

keyDirectObject
                  Description:  A list of Apple event
                                records, one for each
                                menu, each containing the
                                following parameters
                  Descriptor Type:  typeAEList
                  Required or Optional?  Required

   keyMenuID
                  Description:  The ID of the menu, not
                                necessarily equal to the
                                ID of the 'MENU' resource
                                it may have come from
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required
   keyMenuTitle
                  Description:  The title of the menu, as
                                it appears in the menu bar
                  Descriptor Type:  typeChar
                  Required or Optional?  Required
   keyMenuEnabled
                  Description:  Whether or not the menu, as
                                a whole, is enabled
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Required
   keyMenuMDEFID
                  Description:  The ID of the menu definition
                                procedure ('MDEF') resource,
                                ordinarily 0; -1 signifies
                                that the definition procedure
                                is not a resource
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required

keyMenuEventsTattoo
                  Description:  A null parameter to verify
                                that Menu Events handled
                                the event
                  Descriptor Type:  typeNull
                  Required or Optional?  Required

Result Codes
                  mBarNFnd        -126    The application has
                                          no menu bar


Query Menu - list all items in a menu

A Query Menu Apple event asks the application to return a list of records
containing information about all items in a given menu (selected by ID
and/or title).  It requests user interaction to bring the application to the
front, then posts mouse events to simulate a click in the menu bar, with
modifier key states as specified, to force the application to update its
menus, then reads the items from the given menu.  This information is
complete enough to reconstruct the menu, except for the icon resources
referenced by the keyMenuItemIcon parameter.

Event Class       kMEEventClass

Event ID          kAEMEQueryMenu

Parameters

keyMenuID
                  Description:  The ID of the menu, as
                                returned by a Query Menu
                                List Apple event
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Optional
keyMenuTitle
                  Description:  The title of the menu, as
                                returned by a Query Menu
                                List Apple event
                  Descriptor Type:  typeChar
                  Required or Optional?  Optional
NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
keyShiftKeyPressed
                  Description:  Whether the Shift key is
                                pressed at the time of the
                                simulated menu bar click
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false
keyControlKeyPressed
                  Description:  Whether the Control key is
                                pressed at the time of the
                                simulated menu bar click
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false
keyOptionKeyPressed
                  Description:  Whether the Option key is
                                pressed at the time of the
                                simulated menu bar click
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false
keyCommandKeyPressed
                  Description:  Whether the Command key is
                                pressed at the time of the
                                simulated menu bar click
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false

Reply Parameters

keyDirectObject
                  Description:  A list of Apple event
                                records, one for each
                                item, each containing the
                                following parameters
                  Descriptor Type:  typeAEList
                  Required or Optional?  Required

   keyMenuItemID
                  Description:  The ID of the item, numbered
                                from 1 at the top of the menu
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required
   keyMenuItemText
                  Description:  The text of the item, as
                                it appears in the menu
                  Descriptor Type:  typeChar
                  Required or Optional?  Required
   keyMenuItemEnabled
                  Description:  Whether or not the item is
                                enabled
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Required
   keyMenuItemMark
                  Description:  The mark character of the
                                item, in the lower byte
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required
   keyMenuItemIcon
                  Description:  The icon number of the item,
                                which is 256 less than the
                                resource ID of the 'ICON' or
                                'cicn' resource
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required
   keyMenuItemStyle
                  Description:  The style value of the item,
                                in the lower byte
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required
   keyMenuItemCmd
                  Description:  The Command-key equivalent
                                character of the item, in the
                                lower byte
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required

keyMenuEventsTattoo
                  Description:  A null parameter to verify
                                that Menu Events handled
                                the event
                  Descriptor Type:  typeNull
                  Required or Optional?  Required

Result Codes
                  mBarNFnd        -126    The application has
                                          no menu bar
                  errAENoUserInteraction
                                  -1713   The application is
                                          refusing to interact
                                          with other processes
                                          or (if Menu Events
                                          extension is locked)
                                          with remote processes
                  noSuchMenuErr   -15950  The application has
                                          no such menu
                  menuMismatchErr
                                  -15955  The given menu ID
                                          and menu title
                                          do not match


Select Menu Item - perform a menu command

A Select Menu Item event simulates the selection of a command (selected
by item ID and/or item text) from a menu (selected by ID and/or title).  It
requests user interaction to bring the application to the front, then posts
mouse events to simulate the selection of the given menu item, with
modifier key states as specified.  If the Menu event is correctly handled,
and the application reacts to the mouse events in the usual way, the result
is as if the user had actually selected that menu item.  Interaction will fail
if the application refuses to interact with other processes
(kAEInteractWithSelf mode), or, if the application is on another machine
and the Menu Events extension has been locked, if it refuses to interact
with remote processes (kAEInteractWithLocal mode).

Event Class       kMEEventClass

Event ID          kAEMESelectMenuItem

Parameters

keyMenuID
                  Description:  The ID of the menu, as
                                returned by a Query Menu
                                List Apple event
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Required
keyMenuTitle
                  Description:  The title of the menu, as
                                returned by a Query Menu
                                List Apple event
                  Descriptor Type:  typeChar
                  Required or Optional?  Optional
NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
keyMenuItemID
                  Description:  The ID of the item, numbered
                                from 1 at the top of the menu
                  Descriptor Type:  typeShortInteger
                  Required or Optional?  Optional
keyMenuItemText
                  Description:  The text of the item, as
                                it appears in the menu
                  Descriptor Type:  typeChar
                  Required or Optional?  Optional
NOTE:  Either keyMenuItemID or keyMenuItemText, or both, must be
specified.
keyShiftKeyPressed
                  Description:  Whether the Shift key is
                                pressed at the time of the
                                simulated menu selection
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false
keyControlKeyPressed
                  Description:  Whether the Control key is
                                pressed at the time of the
                                simulated menu selection
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false
keyOptionKeyPressed
                  Description:  Whether the Option key is
                                pressed at the time of the
                                simulated menu selection
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false
keyCommandKeyPressed
                  Description:  Whether the Command key is
                                pressed at the time of the
                                simulated menu selection
                  Descriptor Type:  typeBoolean
                  Required or Optional?  Optional
                  Default Value:  false

Reply Parameters

keyMenuEventsTattoo
                  Description:  A null parameter to verify
                                that Menu Events handled
                                the event
                  Descriptor Type:  typeNull
                  Required or Optional?  Required

Result Codes
                  mBarNFnd        -126    The application has
                                          no menu bar
                  errAENoUserInteraction
                                  -1713   The application is
                                          refusing to interact
                                          with other processes
                                          or (if Menu Events
                                          extension is locked)
                                          with remote processes
                  noSuchMenuErr   -15950  The application has
                                          no such menu
                  noSuchMenuItemErr
                                  -15951  The menu has no
                                          such item
                  menuItemDisabledErr
                                  -15952  The item is
                                          disabled
                  menuEventPendingErr
                                  -15953  Another Menu event
                                          is already pending
                                          on this application
                  menuMismatchErr
                                  -15955  The given menu ID
                                          and menu title
                                          do not match
                  menuItemMismatchErr
                                  -15956  The given menu item ID
                                          and menu item text
                                          do not match


Constants defined in the Menu Events suite

Constant               Value

kAEMEQueryMenu         'qmn '
kAEMEQueryMenuList     'qmn#'
kAEMESelectMenuItem    'semi'
keyCommandKeyPressed   'comk'
keyControlKeyPressed   'conk'
keyMenuEnabled         'mnen'
keyMenuEventsTattoo    'M╛nu'
keyMenuID              'mnid'
keyMenuItemCmd         'micm'
keyMenuItemEnabled     'mien'
keyMenuItemIcon        'miic'
keyMenuItemID          'miid'
keyMenuItemMark        'mima'
keyMenuItemStyle       'mist'
keyMenuItemText        'mite'
keyMenuMDEFID          'mndf'
keyMenuTitle           'mnti'
keyOptionKeyPressed    'optk'
keyShiftKeyPressed     'shik'
kMEEventClass          'M╛nu'
menuEventPendingErr    -15953
menuItemDisabledErr    -15952
menuItemMismatchErr    -15956
menuMismatchErr        -15955
noSuchMenuErr          -15950
noSuchMenuItemErr      -15951



Limitations


Some applications refuse to submit to the trickery of Menu Events.  The
prime example is any version of Finder which predates the Power
Macintosh (version 7.1.2).  It is not truly an Apple event server, and it
only respects events of known types.  Any other high-level event is not
replied to, and the send will time out.  ResEdit 2.1.1 is similar.  Some
Microsoft applications handle Apple events in a non-standard fashion,
binding their own event handlers over all Apple event classes, and
therefore should not be targeted.

The only way to know for sure is to try the ones you are interested in
controlling.  Certainly, anything you write yourself is a candidate, as long
as you follow the practices suggested in Apple documentation, namely:  Be
high-level-event-aware.  Always be ready to accept and dispatch an
Apple event.  Assume that any high-level event you don╒t recognize is an
Apple event, and dispatch it as such.  If an unknown event reaches your
wildcard event handler, return errAEEventNotHandled, so that system
event handlers can get a crack at it.  Don╒t deny other programs on the
same machine the right to request user interaction, which is the default.

Another limitation you should know about is that Menu Events can╒t
operate dialogs and alerts which the target application may post in
response to the menu action.  If the menu item text ends in an ellipsis
('╔') character, you can bet that the application will post a dialog or alert
box.  It is then up to the local user to operate the controls.

If the target machine is under the influence of a screen saver or security
package which would present a modal dialog in response to a mouse click,
then Query Menu and Select Menu Item events will time out.  The same is
true if the target machine is already showing a modal dialog, preventing
Menu Events from activating the target application.

A known conflict exists between Menu Events and Help on Wheels.  If you
send a Menu event to an application which does a casual help display
before performing the menu action, and if the help server is running,
problems may occur with the application.  The problem is that the Menu
event╒s user interaction ends when the receiving application sends an
Apple event to the help server, causing it to return to the background.  If
the menu action causes a call to the Standard File Manager or any other
code which should not be called when in the background, the application
may hang.



Programmer Notes


Write to the author at the above address if you want to know more about
the Menu Events extension or how it was programmed.



Acknowledgements


Thanks to C.K. Haun and the other folks at Apple Developer Technical
Support who put together those clever little code snippets which give
folks like me such odd ideas.

Special thanks to the many fine people who beta-tested this software,
including Ken Linger, Chris Reynolds, Michele Marques, Chris Kaltwasser,
James Edward Davis, and Leonard Rosenthol, and to Fred Terry for his
hospitality at the MacScripting mailing list.



Revision History


1.3.1 (December 13, 1997)
Ñ  Public AWOL Utilities 1.4 release.
Ñ  Minor changes to trap patches.

1.3 (March 6, 1996)
Ñ  Public AWOL Utilities 1.3 release.
Ñ  Allowed menus and menu items to be specified using string parameters,
with or without the corresponding numeric ID parameters.  An error is
returned if the numeric and string parameters do not match.
Ñ  Added support for modifier keys (Shift, Control, Option, Command) in
the Query Menu event.
Ñ  Improved application compatibility by simulating a menu bar click, to
force the application to update its menus, before reading the contents of a
menu in response to a Query Menu or Select Menu Item event.
Ñ  Changed the response to a menu selection with the Caps Lock key down
to a simple Apple event recording action, instead of having the target
application send itself a Menu event to invite recording.
Ñ  Added an error string parameter to the reply event when an error
occurs.
Ñ  Moved the error codes from the -21000 range to the -15950 range, so
that errors are reported sensibly in AppleScript alerts.
Ñ  Rewrote ╥Menu Events Sample Script╙ to make use of the new optional
string parameters.

1.2 (October 17, 1994)
Ñ  Public AWOL Utilities 1.2 release.
Ñ  No revisions.

1.1.2 (April 19, 1994)
Ñ  Added support for script recording by forcing high-level-event-aware
applications to send themselves Menu events when the user selects a
menu item and the Caps Lock key is down.
Ñ  Added support for modifier keys (Shift, Control, Option, Command) in
the Select Menu Item event.
Ñ  Removed the nonStandardMenuErr (-21004) code in favor of the new
keyMenuMDEFID parameter in the reply to the Query Menu List event, to
improve compatibility with target applications which use slightly
non-standard menu definition procedures.

1.1.1 (April 11, 1994)
Ñ  Added ╥Menu Events Scripting Addition╙ and ╥Menu Events Sample
Script╙ in place of ╥Menu Events 'aete'╙ resource file.

1.1 (March 28, 1994)
Ñ  Public AWOL Utilities 1.1 release.
Ñ  Documented that Menu Events works with Finder 7.1.2.

1.0.7 (March 13, 1994)
Ñ  Menu Events Help presents a useful message if the user tries to open or
print it when the help server is absent.

1.0.6 (February 27, 1994)
Ñ  Added protection against loading duplicate copies of the extension.

1.0.5 (February 6, 1994)
Ñ  Improved compatibility with At Ease and other applications which flush
mouse-down events when they become active.

1.0.4 (January 30, 1994)
Ñ  If the Shift key is pressed on startup, the extension will not be loaded.
If the Help or Command-? key is pressed, the extension will delay up to
one second to let the user release the key(s).

1.0.3 (January 19, 1994)
Ñ  Added ╥Menu Events 'aete'╙ resource file.

1.0.2 (January 11, 1994)
Ñ  Fixed bug which sent the target application into a notification wait state
if it received a Menu event from a remote sender.

1.0.1 (December 31, 1993)
Ñ  Initial AWOL Utilities 1.0.1 release.